Add auth docs #233
Merged
Add auth docs #233
+1,423
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull Request Overview
This PR introduces initial documentation for authentication and authorization features in ToolHive, covering both CLI and Kubernetes deployment scenarios. The documentation explains how to secure MCP servers using OIDC for authentication and Cedar policies for authorization.
- Comprehensive authentication and authorization guide for Kubernetes deployments
- CLI-focused authentication and authorization guide
- Detailed Cedar policy concepts and configuration documentation
- Conceptual overview of ToolHive's auth framework
- Reusable partial files for common auth-related content
Reviewed Changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/toolhive/guides-k8s/auth-k8s.mdx | Complete guide for setting up auth in Kubernetes with external IdP and service-to-service auth patterns |
| docs/toolhive/guides-cli/auth.mdx | CLI-focused authentication and authorization setup guide |
| docs/toolhive/concepts/cedar-policies.md | Detailed documentation on writing and configuring Cedar authorization policies |
| docs/toolhive/concepts/authentication-authorization.md | Comprehensive conceptual overview of ToolHive's authentication and authorization framework |
| docs/toolhive/concepts/auth-framework.md | Focused conceptual documentation on the auth framework design and benefits |
| docs/toolhive/_partials/_oidc-prerequisites.md | Reusable partial for OIDC prerequisites across auth guides |
| docs/toolhive/_partials/_basic-cedar-config.md | Reusable partial showing basic Cedar policy configuration examples |
| docs/toolhive/_partials/_auth-troubleshooting.md | Reusable partial for common authentication and authorization troubleshooting |
This was referenced Oct 16, 2025
Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com>
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
Remove inline // comments from JSON code block as they are invalid JSON syntax and will cause parsing errors. Move explanations to bullet points above the example for better clarity.
Update all MCPServer YAML examples to use correct CRD field structure: 1. External IdP authentication: - Change spec.auth.oidc → spec.oidcConfig - Add required type: inline field - Nest configuration under inline: key 2. Kubernetes service account authentication: - Change spec.auth.oidc → spec.oidcConfig - Use type: kubernetes instead of inline - Replace clientId with serviceAccount and namespace fields 3. Authorization configuration: - Change spec.auth.authorization → spec.authzConfig - Add required type: configMap field - Update field names: configMapName → name, configMapKey → key These changes align with the actual ToolHive CRD definitions in toolhive/cmd/thv-operator/api/v1alpha1/mcpserver_types.go
Document --follow and --proxy flags for the thv logs command to help users debug authentication issues more effectively: - --follow: Follow logs in real-time (like tail -f) - --proxy: View proxy logs instead of container logs
Add a new approach (Approach 2) showing how to use ConfigMaps to share OIDC configuration across multiple MCPServer resources. This provides: - Centralized management of OIDC settings - Consistency across multiple servers - GitOps-friendly configuration management - Easier multi-server deployments Updated section numbering: - Approach 1: External identity provider (inline config) - Approach 2: Shared OIDC configuration (ConfigMap) - Approach 3: Kubernetes service-to-service (service accounts)
Add an info admonition at the beginning of the auth framework concept document to explicitly clarify that this documentation covers client-to-MCP-server authentication, not MCP-server-to-backend authentication. This distinction helps readers understand: - What is covered: How clients authenticate to the MCP server - What is not covered: How MCP servers authenticate to external APIs (e.g., GitHub MCP server authenticating to GitHub API) The note indicates that MCP-server-to-backend authentication will be covered in separate future documentation.
Revise the "Client support for MCP server authentication" section to reflect the current state of the MCP ecosystem more accurately: - Remove outdated claim that "most clients do not support authentication" - Acknowledge that authentication support varies across clients - Simplify guidance to recommend looking for clients that support MCP authentication standards (OAuth 2.1 and transport-level auth) - Remove redundant use cases section (already covered elsewhere in docs) - Remove "Expected evolution" and "Planning for the future" subsections The revised section is more concise and reflects that while authentication support is not universal, many clients now support it to varying degrees.
…ken diversity This updates the authentication framework concepts documentation to: - Add link to official MCP spec and clarify OAuth resource server role - Update from OIDC-only to OAuth 2.1/OIDC throughout - Document support for both JWT and opaque tokens - Add new "Token validation methods" section explaining local JWT validation and remote token introspection (RFC 7662, Google, GitHub) - Update diagrams to use generic "Access Token" and "Identity Provider" instead of "JWT" and "OIDC Provider" - Update authorization flow from "JWT middleware" to "authentication middleware" - Clarify automatic token type detection (JWT first, then introspection fallback)
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
danbarr
approved these changes
Nov 3, 2025
jhrozek
approved these changes
Nov 3, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Adds documentation for authentication and authorization, including concepts guides for authN/Z and Cedar policies, plus how-to guides for the CLI and K8s operator.
Merge checklist
Content
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.jsonfor moved, renamed, or deleted pages (i.e., if the URL slug changed)Reviews